API Temporal de JavaScript: Manejo Moderno de Fecha y Hora para una Audiencia Global

El objeto `Date` de JavaScript ha sido durante mucho tiempo una fuente de frustración para los desarrolladores. Su mutabilidad, su API inconsistente y su pobre soporte para zonas horarias han llevado a la creación de numerosas bibliotecas como Moment.js y date-fns para llenar los vacíos. Ahora, con la API Temporal, JavaScript ofrece una solución moderna e integrada para manejar fechas y horas con mayor claridad y precisión. Este artículo proporciona una visión general completa de la API Temporal, centrándose en sus características, beneficios y uso en diversos contextos internacionales.

¿Qué es la API Temporal?

La API Temporal es un nuevo objeto global en JavaScript diseñado para solucionar las deficiencias del objeto `Date`. Proporciona una API limpia e inmutable para trabajar con fechas, horas, zonas horarias y sistemas de calendario. De manera crucial, su objetivo es representar los conceptos de fecha y hora de una manera que se alinee más estrechamente con el uso y las expectativas del mundo real, haciendo que la internacionalización sea mucho más sencilla.

Características Clave:

• Inmutabilidad: Los objetos Temporal son inmutables, lo que significa que operaciones como sumar días o meses devuelven nuevos objetos en lugar de modificar el original. Esto elimina una fuente común de errores y hace que el código sea más fácil de razonar.
• API Clara: Temporal proporciona una API consistente e intuitiva para operaciones comunes de fecha y hora.
• Soporte para Zonas Horarias: Temporal incluye un soporte robusto para zonas horarias, permitiéndote trabajar con fechas y horas en diferentes ubicaciones sin las complejidades del antiguo objeto `Date`. Utiliza la base de datos de zonas horarias de la IANA, asegurando información precisa y actualizada.
• Sistemas de Calendario: Más allá del calendario gregoriano, Temporal admite sistemas de calendario alternativos, satisfaciendo las necesidades de diversas culturas y regiones.
• Precisión Mejorada: Temporal ofrece precisión de nanosegundos, abordando las limitaciones del objeto `Date` basado en milisegundos.

Objetos Temporales Básicos

La API Temporal introduce varios tipos de objetos nuevos. Aquí están algunos de los principales:

• `Temporal.PlainDate`: Representa una fecha (año, mes, día) sin zona horaria.
• `Temporal.PlainTime`: Representa una hora (hora, minuto, segundo, milisegundo, microsegundo, nanosegundo) sin fecha ni zona horaria.
• `Temporal.PlainDateTime`: Representa una fecha y hora sin zona horaria.
• `Temporal.ZonedDateTime`: Representa una fecha y hora con una zona horaria específica.
• `Temporal.Instant`: Representa un momento específico en el tiempo, medido en nanosegundos desde la época Unix (1 de enero de 1970 UTC).
• `Temporal.TimeZone`: Representa una zona horaria.
• `Temporal.Duration`: Representa un lapso de tiempo (p. ej., 2 horas, 30 minutos).
• `Temporal.YearMonth`: Representa un año y un mes.
• `Temporal.MonthDay`: Representa un mes y un día.

Trabajando con Fechas

Creando un `Temporal.PlainDate`

Para crear un `Temporal.PlainDate`, puedes usar el constructor:

            const plainDate = new Temporal.PlainDate(2024, 10, 27); // Año, Mes (1-12), Día
console.log(plainDate.toString()); // Salida: 2024-10-27
            

              
                Copy
              
            
          

También puedes usar el método `from`, que acepta una cadena en formato ISO 8601:

            const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Salida: 2024-10-27
            

              
                Copy
              
            
          

Obteniendo Componentes de la Fecha

Puedes acceder a los componentes individuales de la fecha usando propiedades como `year`, `month` y `day`:

            console.log(plainDate.year); // Salida: 2024
console.log(plainDate.month); // Salida: 10
console.log(plainDate.day); // Salida: 27
            

              
                Copy
              
            
          

Aritmética de Fechas

Para sumar o restar días, semanas, meses o años, usa los métodos `plus` y `minus`. Estos métodos devuelven un nuevo objeto `Temporal.PlainDate`:

            const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Salida: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Salida: 2024-09-27
            

              
                Copy
              
            
          

Comparando Fechas

Puedes comparar fechas usando el método `compare`:

            const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Salida: -1 (date1 es anterior a date2)
            

              
                Copy
              
            
          

Trabajando con Horas

Creando un `Temporal.PlainTime`

Para crear un `Temporal.PlainTime`, usa el constructor:

            const plainTime = new Temporal.PlainTime(10, 30, 0); // Hora, Minuto, Segundo
console.log(plainTime.toString()); // Salida: 10:30:00
            

              
                Copy
              
            
          

O usa el método `from` con una cadena de tiempo ISO 8601:

            const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Salida: 10:30:00
            

              
                Copy
              
            
          

Obteniendo Componentes de la Hora

            console.log(plainTime.hour); // Salida: 10
console.log(plainTime.minute); // Salida: 30
console.log(plainTime.second); // Salida: 0
            

              
                Copy
              
            
          

Aritmética de Horas

            const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Salida: 10:45:00
            

              
                Copy
              
            
          

Trabajando con Fecha y Hora Juntas

Creando un `Temporal.PlainDateTime`

Puedes crear un `Temporal.PlainDateTime` directamente o combinando un `Temporal.PlainDate` y un `Temporal.PlainTime`:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Salida: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Salida: 2024-10-27T10:30:00
            

              
                Copy
              
            
          

Zonas Horarias

Manejar correctamente las zonas horarias es crucial para aplicaciones que tratan con usuarios en diferentes ubicaciones. La API Temporal proporciona un soporte robusto para zonas horarias a través de los objetos `Temporal.ZonedDateTime` y `Temporal.TimeZone`.

Creando un `Temporal.ZonedDateTime`

Para crear un `Temporal.ZonedDateTime`, necesitas un `Temporal.PlainDateTime` y un identificador de zona horaria. Los identificadores de zona horaria se basan en la base de datos de zonas horarias de la IANA (p. ej., `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Salida: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (El desfase dependerá de las reglas del DST)

            

              
                Copy
              
            
          

Alternativamente, crea un `Temporal.ZonedDateTime` a partir de un `Instant`.

            const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Marca de tiempo de ejemplo
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Zona horaria como 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());
            

              
                Copy
              
            
          

Convirtiendo Entre Zonas Horarias

Puedes convertir un `Temporal.ZonedDateTime` a una zona horaria diferente usando el método `withTimeZone`:

            const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Salida: 2024-10-27T18:30:00+01:00[Europe/London]
            

              
                Copy
              
            
          

Trabajando con Desfases de Zona Horaria

El método `getOffsetStringFor` del objeto `Temporal.TimeZone` proporciona la cadena de desfase para un `Temporal.Instant` dado:

            const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Salida: -07:00 (Dependiendo de las reglas del DST)
            

              
                Copy
              
            
          

Es esencial usar los identificadores de zona horaria IANA correctos para cálculos precisos. Estos identificadores se mantienen y actualizan regularmente para reflejar los cambios en el horario de verano y los límites de las zonas horarias.

Duraciones

El objeto `Temporal.Duration` representa un lapso de tiempo. Se puede usar para sumar o restar de fechas y horas.

Creando un `Temporal.Duration`

Puedes crear un `Temporal.Duration` usando el constructor, especificando los años, meses, días, horas, minutos, segundos, milisegundos, microsegundos y nanosegundos:

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Años, Meses, Días, Horas, Minutos, Segundos, Milisegundos, Microsegundos, Nanosegundos
console.log(duration.toString()); // Salida: P1Y2M3DT4H5M6.007008009S
            

              
                Copy
              
            
          

O usando una cadena de duración ISO 8601:

            const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Salida: P1Y2M3DT4H5M6S
            

              
                Copy
              
            
          

Sumando Duraciones a Fechas y Horas

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 días
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Salida: 2024-11-03
            

              
                Copy
              
            
          

Ten en cuenta que sumar duraciones que involucran meses o años a las fechas requiere una consideración cuidadosa, ya que el número de días en un mes o año puede variar.

Sistemas de Calendario

La API Temporal admite diferentes sistemas de calendario más allá del calendario gregoriano. Esto es crucial para aplicaciones que necesitan manejar fechas en diversos contextos culturales. Aunque el soporte todavía está evolucionando, proporciona una base para una futura expansión.

Usando Calendarios Alternativos

Para usar un calendario específico, puedes especificarlo al crear objetos Temporal:

            const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // La salida específica puede variar según la implementación y el formato. Requiere polyfill en muchos entornos al momento de escribir esto.
            

              
                Copy
              
            
          

Importante: El soporte para calendarios no gregorianos podría requerir polyfills o soporte específico del navegador/entorno. Consulta la documentación de la API Temporal y las tablas de compatibilidad de navegadores para obtener la información más reciente.

Formateando Fechas y Horas

Aunque la API Temporal se centra en la manipulación de fechas y horas, el formateo generalmente se maneja con el objeto `Intl.DateTimeFormat`, que es parte de la API de Internacionalización. Los objetos Temporal funcionan perfectamente con `Intl.DateTimeFormat`.

Usando `Intl.DateTimeFormat`

Aquí se muestra cómo formatear un `Temporal.PlainDate` usando `Intl.DateTimeFormat`:

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('es-ES', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Salida: 27 de octubre de 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Salida: 27. Oktober 2024
            

              
                Copy
              
            
          

Puedes personalizar las opciones de formato para adaptarlas a tus necesidades. El primer argumento de `Intl.DateTimeFormat` es la configuración regional (locale), que determina el idioma y las convenciones regionales utilizadas para el formato. El uso de diferentes configuraciones regionales (p. ej., 'en-US', 'de-DE', 'fr-FR', 'ja-JP') produce diferentes formatos de salida.

Formateando `Temporal.ZonedDateTime`

Formatear `Temporal.ZonedDateTime` es similar, pero también puedes incluir información de la zona horaria en la salida:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Salida: October 27, 2024, 10:30 AM PDT (La abreviatura de la zona horaria depende de las reglas del DST)
            

              
                Copy
              
            
          

Mejores Prácticas de Internacionalización

Cuando trabajes con fechas y horas en un contexto global, ten en cuenta las siguientes mejores prácticas:

• Usa Identificadores de Zona Horaria IANA: Utiliza siempre identificadores de zona horaria IANA (p. ej., `America/Los_Angeles`, `Europe/London`) para un manejo preciso de la zona horaria.
• Ten en Cuenta el Horario de Verano: El horario de verano (DST) puede afectar los desfases de zona horaria. La API Temporal maneja automáticamente las transiciones de DST.
• Usa `Intl.DateTimeFormat` para Formatear: Utiliza el objeto `Intl.DateTimeFormat` para formatear fechas y horas según la configuración regional del usuario.
• Considera los Sistemas de Calendario: Si tu aplicación necesita dar soporte a usuarios en diferentes contextos culturales, considera el uso de sistemas de calendario alternativos.
• Almacena Fechas y Horas en UTC: Al almacenar fechas y horas en una base de datos, la mejor práctica es almacenarlas en UTC (Tiempo Universal Coordinado) para evitar problemas de zona horaria. Luego, conviértelas a la hora local para fines de visualización. Temporal proporciona métodos para convertir desde y hacia UTC.
• Prueba a Fondo: Prueba tu aplicación con diferentes zonas horarias, configuraciones regionales y sistemas de calendario para asegurarte de que funcione correctamente para todos los usuarios.

Comparando la API Temporal con el Objeto Date Heredado

Aquí hay una tabla que destaca las diferencias clave y las ventajas de la API Temporal en comparación con el objeto `Date` heredado:

Soporte de Navegadores y Polyfills

Como una API relativamente nueva, el soporte de los navegadores para la API Temporal todavía está evolucionando. Consulta las últimas tablas de compatibilidad de navegadores (p. ej., en MDN Web Docs) para ver qué navegadores y entornos la admiten de forma nativa. Para navegadores más antiguos o entornos sin soporte nativo, puedes usar polyfills para proporcionar la funcionalidad de la API Temporal. Busca "Temporal API polyfill" en la web para encontrar opciones adecuadas.

Conclusión

La API Temporal de JavaScript representa un avance significativo en el manejo de fechas y horas en JavaScript. Su inmutabilidad, API clara, soporte robusto para zonas horarias y capacidades de sistemas de calendario la convierten en una herramienta poderosa para los desarrolladores que construyen aplicaciones que necesitan trabajar con fechas y horas de manera precisa y confiable en diversos contextos internacionales. Aunque el soporte de los navegadores todavía está evolucionando, los beneficios de la API Temporal hacen que valga la pena aprenderla y adoptarla para nuevos proyectos. Al adoptar la API Temporal y seguir las mejores prácticas de internacionalización, puedes crear aplicaciones que brinden una experiencia de fecha y hora fluida y precisa para usuarios de todo el mundo.

Lecturas Adicionales

• Documentación Oficial de la API Temporal
• MDN Web Docs sobre Temporal